<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>../www/lib/egr/Persist.pm</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@tree.slackware.lan" />
</head>

<body style="background-color: white">

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<ul>

		<ul>

			<li><a href="#database">DATABASE</a></li>
			<ul>

				<li><a href="#field__id">Field: <code>id</code></a></li>
				<li><a href="#field__typ">Field: <code>typ</code></a></li>
				<li><a href="#field__val">Field: <code>val</code></a></li>
			</ul>

		</ul>

		<li><a href="#methods">METHODS</a></li>
		<ul>

			<li><a href="#method__new__">Method: <code>new()</code></a></li>
			<li><a href="#method__printrecord__">Method: <code>printRecord()</code></a></li>
			<li><a href="#method__prjcreate__">Method: <code>prjCreate()</code></a></li>
			<li><a href="#method__prjexists__">Method: <code>prjExists()</code></a></li>
			<li><a href="#method__prjgetrecordbyid__">Method: <code>prjGetRecordById()</code></a></li>
			<li><a href="#method_prjgetrecordbytype__">Method <code>prjGetRecordByType()</code></a></li>
			<li><a href="#method_prjputrecord__">Method <code>prjPutRecord()</code></a></li>
		</ul>

	</ul>

	<li><a href="#see_also">SEE ALSO</a></li>
	<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>Persist.pm is an object that stores project data in a database.</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The Persist module exposes an object that stores/retrieves project data from a MySQL database. It's job is pretty straightforward, connect to a project in a database and manipuate the project table. The object has various methods to simplify the process.</p>
<p>The Persist object is a TIED variable, any attempt to access the database will cause it to make a connection attempt if it isn't already connected to the database.</p>
<p>It's not possible to connect to just any database. The persist module explicitly uses the Constants.pm connection constants for various database paramerters like UserId and Password.</p>
<p>
</p>
<h3><a name="database">DATABASE</a></h3>
<p>It's hard to talk about the Persist module without discussing the database model. There isn't much of a model to start with, we only use a database for storage, and don't want or use any relational database features. We will probably move away from a database in the future and just use binary file access.</p>
<p>Every EGR project consists of one table in a MySQL database. The table has a random name, so you can't assume that a table name is the a proect. This table contains three fields, id, typ, and val. We should be able to create/modify any type of data structure with these fields including: lists and tress.</p>
<p>
</p>
<h4><a name="field__id">Field: <code>id</code></a></h4>
<p>The id field, is an unsigned bigint and is the row primary key. It is a unuque value, that has no bearing on the other values.</p>
<p>
</p>
<h4><a name="field__typ">Field: <code>typ</code></a></h4>
<p>The typ field is very important. It tells us what type of data the val field contains. Type is a very fluid concept and has little to do with datatypes, but doesn't exclude it. It's an integer value and its meaning is defined in the Constants.pm module. Types can/will come and go throughout the lifetime of the EGR project. It tells us how to interpret the data stored in the next field.</p>
<p>
</p>
<h4><a name="field__val">Field: <code>val</code></a></h4>
<p>The val field is a binary blob that stores data related to the record. It can contain anything and it's meaning is completly dependent on typ.</p>
<p>
</p>
<h2><a name="methods">METHODS</a></h2>
<p>
</p>
<h3><a name="method__new__">Method: <code>new()</code></a></h3>
<p>Static method that allocates a new object.</p>
<p><strong>Usage</strong></p>
<pre>
 my $db = Persist:new();</pre>
<p><strong>Returns</strong></p>
<p>Returns a newly allocated Persist object.</p>
<p>
</p>
<h3><a name="method__printrecord__">Method: <code>printRecord()</code></a></h3>
<p>Prints the entire contents of a record on the console. Helpful when debugging.</p>
<p><strong>Usage</strong></p>
<pre>
 $db-&gt;prjPutRecord($id, $type, $blob);</pre>
<p><strong>Returns</strong></p>
<p>No return value</p>
<p>
</p>
<h3><a name="method__prjcreate__">Method: <code>prjCreate()</code></a></h3>
<p>Creates a new project.</p>
<p><strong>Usage</strong></p>
<pre>
 $db-&gt;prjPutRecord($id, $type, $blob);</pre>
<p><strong>Returns</strong></p>
<p>No return value.</p>
<p>
</p>
<h3><a name="method__prjexists__">Method: <code>prjExists()</code></a></h3>
<p>Returns 1 or 0 if the specified project exists.</p>
<p><strong>Usage</strong></p>
<pre>
 my $id = 0;
 if($db-&gt;prjExists($prjName))
 {
    my @rec = $db-&gt;getRecordById($id);
 }</pre>
<p><strong>Returns</strong></p>
<p>0 = The project does not exist.
1 = The project does exist.</p>
<p>
</p>
<h3><a name="method__prjgetrecordbyid__">Method: <code>prjGetRecordById()</code></a></h3>
<p>Retrieves a record, by it's id.</p>
<p><strong>Usage</strong></p>
<pre>
 my $id = 0;
 if($db-&gt;prjExists($prjName))
 {
    my @rec = $db-&gt;getRecordById($id);
 }</pre>
<p><strong>Returns</strong></p>
<p>An array that contains the record field values.
$array[0] = $id
$array[1] = $typ
$array[2] = $val</p>
<p>
</p>
<h3><a name="method_prjgetrecordbytype__">Method <code>prjGetRecordByType()</code></a></h3>
<p>Returns all records by the specified type.</p>
<p><strong>Usage</strong></p>
<pre>
 if($db-&gt;prjExists($prjName))
 {
    my @rec = $db-&gt;getRecordByType($Constants::PRJ_NAME);
 }</pre>
<p><strong>Returns</strong></p>
<p>An array that contains the record field values.
$array[0] = $id
$array[1] = $typ
$array[2] = $val</p>
<p>
</p>
<h3><a name="method_prjputrecord__">Method <code>prjPutRecord()</code></a></h3>
<p>Stores a record in the project table.</p>
<p><strong>Usage</strong></p>
<pre>
 $db-&gt;prjPutRecord($id, $type, $blob);</pre>
<p><strong>Returns</strong></p>
<p>No return value.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><em>Constants.pm</em></p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2008 Jon Chick &lt;<a href="mailto:chick.jon@egather.org">chick.jon@egather.org</a>&gt;.</p>
<p>Permission is granted to copy, distribute and/or modify this 
document under the terms of the GNU Free Documentation 
License, Version 1.2 or any later version published by the 
Free Software Foundation; with no Invariant Sections, with 
no Front-Cover Texts, and with no Back-Cover Texts.</p>

</body>

</html>
